MODULE = PlPN          PACKAGE = PlPN::TextOutput

#
# Pod::Html is kind of brain-dead:
#
# Place Z<> between function names and parentheses, otherwise Pod::Html
# assumes you meant to put C<...> around it
#
# Put explicit text in all links L<use my text, stupid|some::perl::module>,
# otherwise Pod::Html assumes you want "the X manpage". (Does not apply to
# relative links withing this file.)
#
# It also assumes you want a link if you have C<...> with text matching a
# potential link target. The only way I've found around that is to split it
# up into multiple pieces: C<wo>C<rd>. Looks correct in the resulting HTML,
# but it's ugly to have <code>wo</code><code>rd</code> in the source, and I
# shouldn't have to do it.
#

=head1 NAME

PlPN::TextOutput - The text output window object

=head1 SYNOPSIS

	use PlPN qw(PN);
	
	my $to = PN->GetGlobalOutputWindow;
	$to->AddToolOutput($string);
	
	# etc.

=head1 DESCRIPTION

Allows manipulation of text output windows from Perl.

Note: Currently only the global output window is available; the extensions
interface does not allow access to the individual output windows.

=cut

# we only want the == operator
FALLBACK: TRUE

bool
eq(a,b,swap)
		extensions::ITextOutput* a;
		extensions::ITextOutput* b;
		IV swap;
	OVERLOAD: ==
	CODE:
		RETVAL = (a == b);
	OUTPUT:
		RETVAL

#
# xsubpp only generates the following code for the module, not for the
# individual packages. In our case, that's less than useful, because the
# module does not, in fact, have overloaded operators.
# See the boot section in the generated code for an explanation of what the
# following code does
#
BOOT:
PL_amagic_generation++;
sv_setsv(
	get_sv( "PlPN::TextOutput::()", TRUE ),
	&PL_sv_yes	// or &PL_sv_no or &PL_sv_undef
);
(void)newXSproto_portable("PlPN::TextOutput::()", XS_PlPN_nil, file, "$$$");

=head1 METHODS

=over

=item AddToolOutputZ<>($output, $length = length($output))

Adds output to the window. You may also explicitly set a length if you only
want part of the string.

=cut

void
extensions::ITextOutput::AddToolOutput(output, nLength = -1)
		const wchar_t* output;
		int nLength;
	CLEANUP:
		// caller responsible for freeing memory after utf8_2_wide
		free((void*)output);

=item SetToolBasePathZ<>($path)

Sets the base path for matched error messages in the window.

=cut

void
extensions::ITextOutput::SetToolBasePath(path)
		const wchar_t* path;
	CLEANUP:
		// caller responsible for freeing memory after utf8_2_wide
		free((void*)path);

=item SetToolParserZ<>($parser = undef)

Sets the error message parser for the window. If C<$parser> is false, the
built-in parser is used. Otherwise, C<$parser> will be treated as a regular
expression and used to determine error messages in the window.

=cut

void
extensions::ITextOutput::SetToolParser(customExpression = NULL)
		const char* customExpression;
	CODE:
		// if the user passed something in
		// and it is true according to Perl
		// then we'll use it
		if (items == 2 && (bool)SvTRUE(ST(1))) {
			THIS->SetToolParser(false, customExpression);
		}
		// otherwise we'll use the builtin parser
		else {
			THIS->SetToolParser(true);
		}

=item ClearOutputZ<>()

Clears the output window of all text.

=cut

void
extensions::ITextOutput::ClearOutput()

=item ShowOutputZ<>()

Shows the output window.

=cut

void
extensions::ITextOutput::ShowOutput()

=item HideOutputZ<>()

Hides the output window.

=cut

void
extensions::ITextOutput::HideOutput()

=back

=head1 COPYRIGHT and LICENCE

Copyright (c) 2012 Sean Healy. All rights reserved.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.

=cut
